home *** CD-ROM | disk | FTP | other *** search
- bITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- NAME
- bitmap, bmtoa, atobm - bitmap editor and converter utilities
- for X
-
-
- SYNOPSIS
- bitmap [-options ...] f i l e n a m e W I D T Hx H E I G H T
-
- bmtoa [-chars ...] [ f i l e n a m e]
-
- atobm [-chars c c] [-name v a r i a b l e] [-xhot n u m b e r] [-yhot
- n u m b e r] [ f i l e n a m e]
-
- DESCRIPTION
- The b i t m a p program is a rudimentary tool for creating or
- editing rectangular images made up of 1's and 0's. Bitmaps
- are used in X for defining clipping regions, cursor shapes,
- icon shapes, and tile and stipple patterns.
-
- The b m t o a and a t o b m filters convert b i t m a p files (FILE FOR-
- MAT) to and from ASCII strings. They are most commonly used
- to quickly print out bitmaps and to generate versions for
- including in text.
-
- USAGE
- B i t m a p displays grid in which each square represents a sin-
- gle bit in the picture being edited. Squares can be set,
- cleared, or inverted directly with the buttons on the
- pointer and a menu of higher level operations such as draw
- line and fill circle is provided to the side of the grid.
- Actual size versions of the bitmap as it would appear nor-
- mally and inverted appear below the menu.
-
- If the bitmap is to be used for defining a cursor, one of
- the squares in the images may be designated as the h o t s p o t.
- This determines where the cursor is actually pointing. For
- cursors with sharp tips (such as arrows or fingers), this is
- usually at the end of the tip; for symmetric cursors (such
- as crosses or bullseyes), this is usually at the center.
-
- Bitmaps are stored as small C code fragments suitable for
- including in applications. They provide an array of bits as
- well as symbolic constants giving the width, height, and
- hotspot (if specified) that may be used in creating cursors,
- icons, and tiles.
-
- The W I D T H x H E I G H T argument gives the size to use when creat-
- ing a new bitmap (the default is 16x16). Existing bitmaps
- are always edited at their current size.
-
- If the b i t m a p window is resized by the window manager, the
- size of the squares in the grid will shrink or enlarge to
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 1
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- fit.
-
- OPTIONS
- B i t m a p accepts the following options:
-
- -help
- This option will cause a brief description of the allow-
- able options and parameters to be printed.
-
- -display d i s p l a y
- This option specifies the name of the X server to used.
-
- -geometry g e o m e t r y
- This option specifies the placement and size of the bit-
- map window on the screen. See X for details.
-
- -nodashed
- This option indicates that the grid lines in the work
- area should not be drawn using dashed lines. Although
- dashed lines are prettier than solid lines, on some
- servers they are significantly slower.
-
- -name v a r i a b l e n a m e
- This option specifies the variable name to be used when
- writing out the bitmap file. The default is to use the
- basename of the f i l e n a m e command line argument.
-
- -bw n u m b e r
- This option specifies the border width in piXels of the
- main window.
-
- -fn f o n t
- This option specifies the font to be used in the but-
- tons.
-
- -fg c o l o r
- This option specifies the color to be used for the fore-
- ground.
-
- -bg c o l o r
- This option specifies the color to be used for the back-
- ground.
-
- -hl c o l o r
- This option specifies the color to be used for
- highlighting.
-
- -bd c o l o r
- This option specifies the color to be used for the win-
- dow border.
-
- -ms c o l o r
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 2
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- This option specifies the color to be used for the
- pointer (mouse).
-
- B m t o a accepts the following option:
-
- -chars c c
- This option specifies the pair of characters to use in
- the string version of the bitmap. The first character
- is used for 0 bits and the second character is used for
- 1 bits. The default is to use dashes (-) for 0's and
- sharp signs (#) for 1's.
-
- A t o b m accepts the following options:
-
- -chars c c
- This option specifies the pair of characters to use when
- converting string bitmaps into arrays of numbers. The
- first character represents a 0 bit and the second char-
- acter represents a 1 bit. The default is to use dashes
- (-) for 0's and sharp signs (#) for 1's.
-
- -name v a r i a b l e
- This option specifies the variable name to be used when
- writing out the bitmap file. The default is to use the
- basename of the f i l e n a m e command line argument or leave
- it blank if the standard input is read.
-
- -xhot n u m b e r
- This option specifies the X coordinate of the hotspot.
- Only postive values are allowed. By default, no hotspot
- information is included.
-
- -yhot n u m b e r
- This option specifies the Y coordinate of the hotspot.
- Only postive values are allowed. By default, no hotspot
- information is included.
-
- CHANGING GRID SQUARES
- Grid squares may be set, cleared, or inverted by pointing to
- them and clicking one of the buttons indicated below. Mul-
- tiple squares can be changed at once by holding the button
- down and dragging the cursor across them. Set squares are
- filled and represent 1's in the bitmap; clear squares are
- empty and represent 0's.
-
- B u t t o n 1
- This button (usually leftmost on the pointer) is
- used to set one or more squares. The corresponding
- bit or bits in the bitmap are turned on (set to 1)
- and the square or squares are filled.
-
- B u t t o n 2
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 3
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- This button (usually in the middle) is used to
- invert one or more squares. The corresponding bit
- or bits in the bitmap are flipped (1's become 0's
- and 0's become 1's).
-
- B u t t o n 3
- This button (usually on the right) is used to clear
- one or more squares. The corresponding bit or bits
- in the bitmap are turned off (set to 0) and the
- square or squares are emptied.
-
- MENU COMMANDS
- To make defining shapes easier, b i t m a p provides 13 commands
- for drawing whole sections of the grid at once, 2 commands
- for manipulating the hotspot, and 2 commands for updating
- the bitmap file and exiting. A command buttons for each of
- these operations is located to the right of the grid.
-
- Several of the commands operate on rectangular portions of
- the grid. These areas are selected after the command button
- is pressed by moving the cursor to the upper left square of
- the desired area, pressing a pointer button, dragging the
- cursor to the lower right hand corner (with the button still
- pressed) , and then releasing the button. The command may
- be aborted by pressing any other button while dragging or by
- releasing outside the grid.
-
- To invoke a command, move the pointer over that command and
- click any button.
-
- C l e a r A l l
- This command is used to clear all of the bits in
- the bitmap as if Button 3 had been dragged through
- every square in the grid. It cannot be undone.
-
- S e t A l l
- This command is used to set all of the bits in the
- bitmap as if Button 1 had been dragged through
- every square in the grid. It cannot be undone.
-
- I n v e r t A l l
- This command is used to invert all of the bits in
- the bitmap as if Button 2 had been dragged through
- every square in the grid.
-
- C l e a r A r e a
- This command is used to clear a region of the grid
- as if Button 3 had been dragged through each of the
- squares in the region. When this command is
- invoked, the cursor will change shape to indicate
- that the area to be cleared should be selected as
- outlined above.
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 4
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- S e t A r e a
- This command is used to set a region of the grid as
- if Button 1 had been dragged through each of the
- squares in the region. When this command is
- invoked, the cursor will change shape to indicate
- that the area to be set should be selected as out-
- lined above.
-
- I n v e r t A r e a
- This command is used to inverted a region of the
- grid as if Button 2 had been dragged through each
- of the squares in the region. When this command is
- invoked, the cursor will change shape to indicate
- that the area to be inverted should be selected as
- outlined above.
-
- C o p y A r e a
- This command is used to copy a region of the grid
- from one location to another. When this command is
- invoked, the cursor will change shape to indicate
- that the area to be copied should be selected as
- outlined above. The cursor should then be clicked
- on the square to which the upper left hand corner
- of the region should be copied.
-
- M o v e A r e a
- This command is used to move a region of the grid
- from one location to another. When this command is
- invoked, the cursor will change shape to indicate
- that the area to be moved should be selected as
- outlined above. The cursor should then be clicked
- on the square to which the upper left hand corner
- of the region should be moved. Any squares in the
- region's old position that aren't also in the new
- position are cleared.
-
- O v e r l a y A r e a
- This command is used to copy all of the set squares
- in a region of the grid from one location to
- another. When this command is invoked, the cursor
- will change shape to indicate that the area to be
- copied should be selected as outlined above. The
- cursor should then be clicked on the square to
- which the upper left hand corner of the region
- should be overlaid. Only the squares that are set
- in the region will be touched in the new location.
-
- L i n e
- This command will set the squares in a line between
- two points. When this command is invoked, the cur-
- sor will change shape to indicate that the pointer
- should be clicked on the two end points of the
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 5
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- line.
-
- C i r c l e
- This command will set the squares on a circle
- specified by a center and a point on the curve.
- When this command is invoked, the cursor will
- change shape to indicate that the pointer should be
- clicked on the center of the circle and then over a
- point on the curve. Small circles may not look
- very round because of the size of the grid and the
- limits of having to work with discrete pixels.
-
- F i l l e d C i r c l e
- This command will set all of the squares in a cir-
- cle specified by a center and a point on the curve.
- When this command is invoked, the cursor will
- change shape to indicate that the pointer should be
- clicked on the center of the circle and then over a
- point on the curve. All squares side and including
- the circle are set.
-
- F l o o d F i l l
- This command will set all clear squares in an
- enclosed shape. When this command is invoked, the
- cursor will change shape to indicate that the
- pointer should be clicked on any empty square
- inside the shape to be filled. All empty squares
- that border horizontally or vertically with the
- indicated square are set out to the enclosing
- shape. If the shape is not closed, the entire grid
- will be filled.
-
- S e t H o t S p o t
- This command designates one square in the grid as
- the hot spot if this bitmap to be used for defining
- a cursor. When the command is invoked, the cursor
- will change indicating that the pointer should be
- clicked on the square to contain the hot spot.
-
- C l e a r H o t S p o t
- This command removes any designated hot spot from
- the bitmap.
-
- W r i t e O u t p u t
- This command writes a small fragment of C code
- representing the bitmap to the filename specified
- on the command line. If the file already exists,
- the original file will be renamed to f i l e n a m e~
- before the new file is created. If an error occurs
- in either the renaming or the writing of the bitmap
- file, a dialog box will appear asking whether or
- not b i t m a p should use / t m p/ f i l e n a m e instead.
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 6
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- Q u i t
- This command causes b i t m a p to display a dialog box
- asking whether or not it should save the bitmap (if
- it has changed) and then exit. Answering y e s is
- the same as invoking W r i t e O u t p u t; n o causes b i t m a p
- to simply exit; and c a n c e l will abort the Q u i t com-
- mand so that more changes may be made.
-
- FILE FORMAT
- The W r i t e O u t p u t command stores bitmaps as simple C program
- fragments that can be compiled into programs, referred to by
- X Toolkit pixmap resources, manipulated by other programs
- (see x s e t r o o t), or read in using utility routines in the
- various programming libraries. The width and height of the
- bitmap as well as the hotspot, if specified, are written as
- preprocessor symbols at the start of the file. The bitmap
- image is then written out as an array of characters:
-
- #define namewidth 11
- #define nameheight 5
- #define namexhot 5
- #define nameyhot 2
-
- static char namebits[] = {
- 0x91, 0x04, 0xca, 0x06, 0x84,
- 0x04, 0x8a, 0x04, 0x91, 0x04
- };
-
- The name prefix to the preprocessor symbols and to the bits
- array is constructed from the f i l e n a m e argument given on the
- command line. Any directories are stripped off the front of
- the name and any suffix beginning with a period is stripped
- off the end. Any remaining non-alphabetic characters are
- replaced with underscores. The n a m e x h o t and n a m e y h o t
- symbols will only be present if a hotspot has been desig-
- nated using the S e t H o t S p o t command.
-
- Each character in the the array contains 8 bits from one row
- of the image (rows are padded out at the end to a multiple
- of 8 to make this is possible). Rows are written out from
- left to right and top to bottom. The first character of the
- array holds the leftmost 8 bits of top line, and the last
- characters holds the right most 8 bits (including padding)
- of the bottom line. Within each character, the leftmost bit
- in the bitmap is the least signficant bit in the character.
-
- This process can be demonstrated visually by splitting a row
- into words containing 8 bits each, reversing the bits each
- word (since Arabic numbers have the significant digit on the
- right and images have the least significant bit on the
- left), and translating each word from binary to hexidecimal.
-
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 7
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- In the following example, the array of 1's and 0's on the
- left represents a bitmap containing 5 rows and 11 columns
- that spells X 1 1. To its right is is the same array split
- into 8 bit words with each row padded with 0's so that it is
- a multiple of 8 in length (16):
-
- 10001001001 10001001 00100000
- 01010011011 01010011 01100000
- 00100001001 00100001 00100000
- 01010001001 01010001 00100000
- 10001001001 10001001 00100000
-
- Reversing the bits in each word of the padded, split version
- of the bitmap yields the left hand figure below. Interpret-
- ting each word as hexidecimal number yields the array of
- numbers on the right:
-
- 10010001 00000100 0x91 0x04
- 11001010 00000110 0xca 0x06
- 10000100 00000100 0x84 0x04
- 10001010 00000100 0x8a 0x04
- 10010001 00000100 0x91 0x04
-
- The character array can then be generated by reading each
- row from left to right, top to bottom:
-
- static char namebits[] = {
- 0x91, 0x04, 0xca, 0x06, 0x84,
- 0x04, 0x8a, 0x04, 0x91, 0x04
- };
-
- The b m t o a program may be used to convert b i t m a p files into
- arrays of characters for printing or including in text
- files. The a t o b m program can be used to convert strings
- back to b i t m a p format.
-
- USING BITMAPS IN PROGRAMS
- The format of b i t m a p files is designed to make bitmaps and
- cursors easy to use within X programs. The following code
- could be used to create a cursor from bitmaps defined in
- t h i s. c u r s o r and t h i s m a s k. c u r s o r:
-
- #include "this.cursor"
- #include "thismask.cursor"
-
- XColor foreground, background;
- /* fill in foreground and background color structures */
- Pixmap source = XCreateBitmapFromData (display, drawable,
- thisbits, thiswidth, thisheight);
- Pixmap mask = XCreateBitmapFromData (display, drawable,
- thismaskbits, thismaskwidth, thismaskheight);
- Cursor cursor = XCreatePixmapCursor (display, source, mask,
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 8
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- foreground, background, thisxhot, thisyhot);
-
-
- Additional routines are available for reading in b i t m a p
- files and returning the data in the file, in Bitmap
- (single-plane Pixmap for use with routines that require
- stipples), or full depth Pixmaps (often used for window
- backgrounds and borders). Applications writers should be
- careful to understand the difference between Bitmaps and
- Pixmaps so that their programs function correctly on color
- and monochrome displays.
-
- For backward compatibility, b i t m a p will also accept X10 for-
- mat b i t m a p files. However, when the file is written out
- again it will be in X11 format
-
- X DEFAULTS
- B i t m a p uses the following resources:
-
- Background
- The window's background color. Bits which are 0 in the
- bitmap are displayed in this color. This option is use-
- ful only on color displays. The default value is w h i t e.
-
- BorderColor
- The border color. This option is useful only on color
- displays. The default value is b l a c k.
-
- BorderWidth
- The border width. The default value is 2.
-
- BodyFont
- The text font. The default value is v a r i a b l e.
-
- Foreground
- The foreground color. Bits which are 1 in the bitmap
- are displayed in this color. This option is useful only
- on color displays. The default value is b l a c k.
-
- Highlight
- The highlight color. b i t m a p uses this color to show the
- hot spot and to indicate rectangular areas that will be
- affected by the M o v e A r e a, C o p y A r e a, S e t A r e a, and
- I n v e r t A r e a commands. If a highlight color is not
- given, then b i t m a p will highlight by inverting. This
- option is useful only on color displays.
-
- Mouse
- The pointer (mouse) cursor's color. This option is use-
- ful only on color displays. The default value is b l a c k.
-
-
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 9
-
-
-
-
-
-
- BITMAP(1) USER COMMANDS BITMAP(1)
-
-
-
- Geometry
- The size and location of the bitmap window.
-
- Dimensions
- The W I D T H x H E I G H T to use when creating a new bitmap.
-
- SEE ALSO
- X(1), X l i b - C L a n g u a g e X I n t e r f a c e (particularly the sec-
- tion on M a n i p u l a t i n g B i t m a p s), X m u R e a d B i t m a p D a t a F r o m F i l e
-
- BUGS
- The old command line arguments aren't consistent with other
- X programs.
-
- If you move the pointer too fast while holding a pointer
- button down, some squares may be missed. This is caused by
- limitations in how frequently the X server can sample the
- pointer location.
-
- There is no way to write to a file other than the one speci-
- fied on the command line.
-
- There is no way to change the size of the bitmap once the
- program has started.
-
- There is no u n d o command.
-
- COPYRIGHT
- Copyright 1988, Massachusetts Institute of Technology.
- See X( 1) for a full statement of rights and permissions.
-
- AUTHOR
- b i t m a p by Ron Newman, MIT Project Athena; documentation,
- b m t o a, and a t o b m by Jim Fulton, MIT X Consortium.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Sun Release 3.2 Last change: 28 October 1988 10
-
-
-
-
-